Roller

	This plug-in is written in Python 2.7 for GIMP v2.10. It is recommended for computers with 16 gigabytes or more of RAM. Roller is designed to create image compositions like wallpaper, image boards, collages, etc. Roller 1 and Roller 2 presets are incompatible with Roller 3.

Basics
	Steps

	Steps are linear and dependent on successiveness. Consecutive steps depend upon previous steps. Typically a step will create a layer, but sometimes a step will only influence the steps that follow it. As steps are rendered, they are added to the composition at the top of the layer stack. In the navigation lists, the steps are ordered consecutively. A step at the top of a navigation list is performed before a step below it. Layers from steps at the bottom of a navigation list end up on top of layers made from steps at the top of a list.

    Preview and Plan Buttons
    
    The Preview and Plan buttons produce results up to their step. Changes to a previous step cause its latter steps to have invalid results, and thus, cause them to redo themselves when they already have production.

	Composition

	There are several layers to be aware of when creating a composition. They are the backdrop-image, backdrop-style, gradient light, and a model layer group.

	Every composition has a backdrop-image layer. This layer serves as a potential backdrop for the composition and sometimes provides material for a backdrop-style layer.

	A backdrop-style layer is positioned above the backdrop-image layer. The style layer's purpose is to add interest to the backdrop of the composition. Some of the backdrop-styles require material from the backdrop-image to produce a result. If the backdrop-image layer has material, the backdrop-image's mask applies to the backdrop-style.

	The gradient light is a gradient that is applied to multiple layers in a render. It's purpose is to simulate a light source, but it has other uses, such as mixing up a backdrop-style, or unifying a composition.

	The gradient light's option, Decoration, refers to plaque, fringe, and border material.

	Model groups come in two designs, a custom cell and a table. Model groups have multiple steps. Both designs have very similar steps, but differ in how image material is placed. A custom cell is useful for placing one image at a time, while the table model is useful for placing multiple images on a layer.

User-Interface

	Views are designed to be an easily canceled or accepted. Pressing the Esc key will cancel any window, and the Return key will accept a window depending on the widget in focus. Views dynamically resize so that screen-space is not wasted, and Roller doesn't have to use scroll-bars. A view can be stretched, but the stretch won't stick during a window resize. When Roller adds an option groups during its first appearance, the draw process will cause a window flicker.

Insights

	Image Place

		Several stages transpire when Roller assigns an image to a cell. Before an image is placed, a Cell Rectangle, a Cell Pocket, an Image Shift, and an Image Mold are calculated.

		The Cell Rectangle

		Every cell, no matter its shape, has a rectangle that defines the cell bounds. Cell Rectangles can be calculated automatically or defined by the user with the Cell Size or the Custom Cell Rectangle options.

		The Cell Pocket

		The Cell Pocket is a rectangle calculated from the Cell Rectangle as a result of computing the cell margins. Images are placed inside this rectangle. If the image is rotated, it is rotated so that it fits inside the Cell Pocket.

		Image Shift

		The Shift options modify the Cell Pocket or ignore it. In other words, the Cell Pocket is no longer the limiting factor in the image placement. If the Shift option Jitter is used, the image is resized to the Cell Pocket, but it is not fitted to the Cell Pocket after it is rotated.

		Image Mold

		The Mold process ensures that an image fits inside the Cell Pocket. If an image is larger than the Cell Pocket, it may be down-sized depending on the Resize Method. Depending on the Resize Methods and image justification, the image may be enlarged in order to fill the Cell Pocket.

	Grid

		This can be a frustrating aspect of the per cell tables. Switching Grid Types causes a new grid cell table to be created, and with it, the dependent per cell tables. Also, reducing and increasing a cell table's size will reset the cells that are removed and then added back. Try saving cell tables as a preset before changing the Grid Type.

	Plaque

		Depending on the Obey Margins setting, a plaque can be the cell shape that fits inside the Cell Rectangle or the cell shape that fits insdie the Cell Pocket.

		This is the pipeline for the plaque process:
			
		Add plaque material, mask, feather, apply mode, bump, blur behind, cast shadow, and apply gradient light.

	Fringe

		Depending on the Obey Margins setting, fringe is applied to the cell shape that fits inside the Cell Rectangle or the cell shape that fits insdie the Cell Pocket.

		This is the pipeline for the fringe process:
		
		Add fringe material, apply mode, bump, cast shadow, and apply gradient light.

	Border
	
		This is the pipeline for the border process:

		Draw border material, border blur, emboss, blur behind, cast shadow, and apply gradient light.
	
How to Add Frames to the Frame Cover Image-effect

	When Roller is first started, the Frame Cover image-effect creates a list of the '.png' file types from Roller's Frame folder. You can add additional frames to this folder. In order to add your own frames, they must be the '.png' file type.

	Thank you dinasset from 'gimpchat.com' for sharing the frame files.

Errors And Limitations To Be Aware Of

	* Opening and closing images in GIMP while the plug-in is running will likely make it unstable. I recommend not using the GIMP interface while the plug-in is running, except for performing tasks that are undone.

	* Ellipse and hexagonal shaped cells are double-spaced. Every other cell in their cell arrangement is empty.

	* If you see a GIMP warning, "Roller is unable to load a preset in its original state.", then one or more of the options in the preset has been removed, which is seldom, or typically replaced with a different named option. This occurs when I realize I need to create a better description for an option. This also happens when I am expanding Roller. In this case, an option name has been renamed as it is out of sync with a new naming convention where a pattern has formed from the expansion process. When this happens, the rest of the options in the preset are still intact.

	* Putting too many rows and columns into a composition grid may result in a crash. GTK has its limitations, and Roller doesn't compensate for a grossly large scale. The Merge Cells window will be the slowest cell window drawing cells. I was able to create a grid of 15 rows and 15 columns without too much of a delay. So patience may be in order if you wish to create a larger grid of cells.

	* I recommend having the Layer Dock visible while running the plug-in as this dock will show GIMP working as the plug-in is running.

	* If external files are referenced, the files are opened during a render or a preview process. GIMP will show the loading process in its status bar at the bottom of the GIMP window.

	* Two running Roller scripts will likely crash into each other.

	* When the script is run for the first time, Python creates ".pyc" type files within the module folder. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so no worries about deleting them.

    * Some dynamic brushes do not work with the functions that require a brush stroke. These functions would include Brush Punch, Brush Edge, and Fringe.

Links
	These are GIMP-related sites worth visiting:

	* I post the latest version of my GIMP plug-ins on GitHub under my GummyCowboy user-name:
	github.com/gummycowboy

	* Forum:
	gimplearn.net
	gimpchat.com
	gimp-forum.net
	gimpusers.com

	* Plug-in:
	gimpscripts.net
	sourceforge.net/projects/gimp-tools
	magentacloud.de/share/x2qpdqu2g4#$/Plug-Ins
	kmarkku.arkku.net/Path_modify_files/Gimp_master.html
	gmic.eu
	gitlab.gnome.org/GNOME/gimp/-/tree/gimp-2-10
	gimpbook.com/scripting/

	* Other:
	gimp-forum.net/Thread-Paths-Basics
	alessandrofrancesconi.it/projects/bimp
	discuss.pixls.us

	* GEGL:
	gegl.org/operations
	gimpchat.com/viewtopic.php?f=9&t=18040
	gimp-forum.net/Thread-Scripting-GEGL-operations
	samjcreations.blogspot.com/2020/09/est-une-bibliotheque-image-libre-tres.html
	gimpchat.com/viewtopic.php?f=10&t=19463

	* Frames:
	gimpchat.com/viewtopic.php?f=9&t=11486

	* Wrap an image around an object:
	youtube.com/watch?v=rUp3-XxZl0E
	youtube.com/watch?v=qoTjcXR_bFk

	* PyGTK
	Reference Manual:
	wiki.python.org.br/DocumentacaoPython?action=AttachFile&do=get&target=ref.pdf

	Documentation:
	library.isr.ist.utl.pt/docs/pygtk2reference/

	* Tutorial:
	developer.ibm.com/articles/os-autogimp/
    littlewebhut.com/gimp/
	graphicdesign.stackexchange.com/questions/87247/creating-a-realistic-gold-surface-in-gimp
	
	* Python
	www.gimp.org/docs/python/
	discuss.pixls.us/t/gmic-tutorial-fragments/24289/63
	gmic-py.readthedocs.io/en/latest/gettingstarted.html#run-a-simple-g-mic-effect-and-view-it
	inventwithpython.com/bigbookpython/
	docs.python.org/3/library/2to3.html
    projects.raspberrypi.org/en/codeclub/python-module-1
	automatetheboringstuff.com/2e/chapter0/
	pythondiscord.com/resources/
	wiki.python.org/moin/BeginnersGuide
	practicalpython.yasoob.me/toc.html

	* Get GIMP ("GNU Image Manipulation Program")
	gimp.org

	* YouTube
	Rich2005
	Make GIMP Brush
	youtube.com/watch?v=3mZ9vF2ayM0

	Davies Media Design
	youtube.com/channel/UCq79-lfj2w7oRXGRcOP2B7g

	tutor4u
	youtube.com/watch?v=ToHF7OhkjTM&list=PLA4BBBE09E8E82409

	Jackson Bates - GIMP Scripting Python Fu Playlist
	youtube.com/watch?v=cPQRxZo9BJE&list=PLyRItRv4aHfOuUC8a1SMeTLV08wxdnWt-&index=1

Special Thanks

	Many thanks to the free programs Notepad++ (for easy editting), Visual Studio Code (for syntax checking), and PyCharm (for detailed code analysis). Each is a great Python code editor. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their inspirational work.

Stairway to Heaven

    And as we wind on down the road
    Our shadows taller than our soul
    There walks a lady we all know
    Who shines white light and wants to show
    How everything still turns to gold
    And if you listen very hard
    The tune will come to you at last
    When all are one and one is all
    To be a rock and not to roll

     Led Zeppelin
